Note: This is one of three alternative implementations for NEO-1055. See also:

• feat: add useAttribute hook for boolean property ↔ attribute reflection #99 — Standalone useAttribute hook (boolean-only, cooperative with component.ts)
• feat: add reflect option to useProperty for property-attribute reflection #100 — reflect option added to existing useProperty hook

Summary

• Adds a standalone useAttribute hook that provides bidirectional property ↔ attribute sync with built-in type coercion, loop prevention, and MutationObserver-based attribute observation
• Unlike useProperty with reflect, useAttribute is fully self-contained — no need to declare observedAttributes separately
• Supports Boolean, String, and Number types with automatic coercion and optional custom defaults

API

const [opened, setOpened] = useAttribute('opened', Boolean);           // default: false
const [name, setName] = useAttribute('name', String, 'unnamed');       // custom default
const [count, setCount] = useAttribute('count', Number);               // default: 0

Signature: useAttribute<T>(name: string, type: AttributeType, defaultValue?: T): StateTuple<T>

How it works

• Uses a shared MutationObserver per host element (stored via symbol) to observe attribute changes — no observedAttributes declaration needed
• Loop prevention via reflectingSymbol: when the hook reflects a property to an attribute, it sets a flag so the MutationObserver callback skips self-caused changes
• Type coercion table:

Features

• Property → attribute reflection (automatic)
• Attribute → property sync (via MutationObserver)
• *-changed event dispatch (cancelable, same convention as useProperty)
• preventDefault() blocks both property and attribute update
• Function updater pattern: setCount(prev => prev + 1)
• Kebab-case attribute ↔ camelCase property conversion
• Compatible with lift() pattern for parent-controlled state
• Honors initial HTML attributes (<el opened>)
• Respects parent .prop= bindings
• Shared MutationObserver across multiple useAttribute calls on same host
• Proper teardown on disconnect

Test coverage

22 test cases covering:

• Boolean, String, Number types with reflection
• Initial attribute values and custom defaults
• Function updater pattern
• Feedback loop prevention
• External setAttribute/removeAttribute via MutationObserver
• Event dispatch and preventDefault
• Kebab-case ↔ camelCase conversion
• Lift pattern with parent/child
• Multiple useAttribute hooks on same host
• No observedAttributes required
• Parent .prop= override

All 91 tests pass (existing + new).

Files changed

Closes NEO-1055